#pragma once
/*--------------------------------------------------------------------------------
 * Adaptive Intelligence - Foundation Framework Class Library
 * Version 2.00
 * 
 * Socket Connection Interface
 *		Provides the interface definition for classes which implement inbound- or 
 * outbound-originated Sockets connections.
 *------------------------------------------------------------------------------*/

/*--------------------------------------------------------------------------------
 * System Imports
 *------------------------------------------------------------------------------*/
#include "stdafx.h"
using namespace System;

namespace Adaptive
{
	namespace Network
	{
		namespace Sockets
		{
			/// <summary>
			/// Provides the interface definition for classes which implement inbound- or 
			/// outbound-originated Sockets connections.
			/// </summary>
			/// <remarks>
			/// This interface represents both client Sockets connections and Socket connection
			/// instances accepted by a Sockets daemon.
			/// </remarks>
			public interface class ISocketConnection
			{
			public:
				/// <summary>
				/// Gets a value indicating whether the socket is connected to a remote host.
				/// </summary>
				/// <summary>
				/// <b>true</b> if a socket connection is established; otherwise, <b>false</b>.
				/// </summary>
				property bool Connected{ bool get(); }
				/// <summary>
				/// Gets a value indicating whether pending, unread data is present in the buffer.
				/// </summary>
				/// <summary>
				/// <b>true</b> if data is present waiting to be read; otherwise, <b>false</b>.
				/// </summary>
				property bool HasData{ bool get(); }
				/// <summary>
				/// Gets a unique ID for the socket connection instance.
				/// </summary>
				/// <summary>
				/// The underlying socket handle as a string.
				/// </summary>
				property String^ Id { String^ get(); }
				/// <summary>
				/// Closes the connection.
				/// </summary>
				void Close();
				/// <summary>
				/// Reads a byte from the inbound data buffer.
				/// </summary>
				/// <returns>
				/// A byte value.
				/// </returns>
				Byte ReadByte();
				/// <summary>
				/// Reads all pending data from tne inbound data buffer.
				/// </summary>
				/// <returns>
				/// A byte array containing the data that was read, or <b>null</b>
				/// if no data was read.
				/// </returns>
				array<Byte>^ ReadAllBytes();
				/// <summary>
				/// Reads the specified number of bytes of pending data from tne inbound data buffer.
				/// </summary>
				/// <param name="numberOfBytes">The number of bytes to be read.</param>
				/// <returns>
				/// A byte array containing the data that was read, or <b>null</b>
				/// if no data was read.
				/// </returns>
				array<Byte>^ ReadBytes(int numberOfBytes);
				/// <summary>
				/// Reads the inbound data buffer contents as a string.
				/// </summary>
				/// <returns>
				/// A string containing the buffer contents, or <see cref="String::Empty"/> if no data is present.
				/// </returns>
				String^		ReadString();
				/// <summary>
				/// Sends data to a remote host.
				/// </summary>
				/// <param name="contentToSend">A byte array containing the content to be sent.</param>
				/// <returns>The total number of bytes transmitted.</returns>
				int	Send(array<Byte>^ contentToSend);
				/// <summary>
				/// Sends data to a remote host.
				/// </summary>
				/// <param name="contentToSend">A short integer to be sent.</param>
				/// <returns>The total number of bytes transmitted.</returns>
				int	Send(short contentToSend);
				/// <summary>
				/// Sends data to a remote host.
				/// </summary>
				/// <param name="contentToSend">An integer to be sent.</param>
				/// <returns>The total number of bytes transmitted.</returns>
				int	Send(int contentToSend);
				/// <summary>
				/// Sends data to a remote host.
				/// </summary>
				/// <param name="contentToSend">A long integer to be sent.</param>
				/// <returns>The total number of bytes transmitted.</returns>
				int	Send(__int64 contentToSend);
				/// <summary>
				/// Sends data to a remote host.
				/// </summary>
				/// <param name="contentToSend">A character to be sent.</param>
				/// <returns>The total number of bytes transmitted.</returns>
				int	Send(char contentToSend);
				/// <summary>
				/// Sends data to a remote host.
				/// </summary>
				/// <param name="contentToSend">An unsigned characer (or byte) t to be sent.</param>
				/// <returns>The total number of bytes transmitted.</returns>
				int	Send(unsigned char contentToSend);
				/// <summary>
				/// Sends data to a remote host.
				/// </summary>
				/// <param name="contentToSend">A string containing the content to be sent.</param>
				/// <returns>The total number of bytes transmitted.</returns>
				int Send(String^ contentToSend);
				/// <summary>
				/// Sends data to a remote host.
				/// </summary>
				/// <param name="contentToSend">A string containing the content to be sent.</param>
				/// <param name="sendInAscii">
				/// A vlaue indicating whether to convert the Unicode string to a standard ASCII string.
				/// </param>
				/// <returns>The total number of bytes transmitted.</returns>
				int Send(String^ contentToSend, bool sendInAscii);
				/// <summary>
				/// Waits for the specified data to appear in the buffer.
				/// </summary>
				/// <param name="dataToWaitFor">A byte array containing the data to wait for.</param>
				/// <param name="timeOutValue">
				/// The timeout value, in seconds.
				/// </param>
				/// <returns>The data that was read during the operation.</returns>
				array<Byte>^	WaitForData(array<Byte>^ dataToWaitFor, int timeOutValue);
				/// <summary>
				/// Waits for the specified data to appear in the buffer.
				/// </summary>
				/// <param name="dataToWaitFor">A string containing the data to wait for.</param>
				/// <param name="timeOutValue">
				/// The timeout value, in seconds.
				/// </param>
				/// <returns>The data that was read during the operation.</returns>
				String^			WaitForStringData(String^ dataToWaitFor, int timeOutValue);
			};
		}
	}
}